Refresh + simplify the epic template #16652

loujaybee · 2023-03-03T09:37:12Z

I've recently been updating IDE team epics with @laushinka and we were looking back at this template for inspiration, however noticed a few things that I think would improve the template generally. Example implementation of the template:

Epic: User Configurable Workspace Timeouts (CLI command + user preference) #9038

Some changes / reasoning.

Make clear this is for user-facing work, not tech debt or investigations/discovery - I believe the fields / properties required for those types of work are too different from this template that it would not be of value. We should consider making more epic template for these different types of epics.
Remove (almost all) placeholders I wasn't sure how much the placeholders were adding value to the template, they make it feel quite overwhelming to me.
Make all fields optional - Yes, an argument can be made for some fields being required but I believe being more liberal will increase usage of the template.

Release Notes

NONE

loujaybee · 2023-03-03T10:46:23Z

.github/ISSUE_TEMPLATE/epic.yml

 title: "Epic: "
 labels: ["type: epic"]
 body:
- type: markdown
-  attributes:
-    value: Before raising an epic, please search for existing epics[[1](https://github.com/gitpod-io/gitpod/issues?q=is%3Aopen+is%3Aissue+label%3A%22type%3A+epic%22)][[2](https://github.com/gitpod-io/gitpod/issues?q=is%3Aopen+is%3Aissue+%22Epic%3A+%22)] to avoid creating duplicates. Read more about [Epics](https://www.notion.so/gitpod/Development-Process-2-0-6681854173ab4d2f92880f9f3d85cab5#321619f5a4bd4391be83c66feb2cdb49) (internal) in **Development Process**.


I believe this "don't duplicate" can be implied, I'm not sure it adds much value, only select Gitpodders are really creating or concerned with epics. Also, I think we should remove the template from the RFC, and have this template as the single source of truth, making a link back redundant.

loujaybee · 2023-03-03T10:47:23Z

.github/ISSUE_TEMPLATE/epic.yml

 - type: textarea
-  id: summary
+  id: press-release


Removed summary, pulled the press release field up top. @laushinka mentioned we could rename, however I would suggest to keep for now, since it's part of the (well documented) PRFAQ framework, so by keeping the name it makes it more clear that it's aligned with that philosophy. As with all other fields, is now optional, though.

suggestion: A better alternative could be Release Notes. However, this would require us to be more intentional with this field and how we use it. Let's give it a go.

loujaybee · 2023-03-03T10:48:13Z

.github/ISSUE_TEMPLATE/epic.yml

-    description: If we do X, we expect Y
-    placeholder: Can be useful if the work is explicitly experimental.
+    description: Optionally specifiy which user will be impacted by this change? 
+    placeholder: [Developer/Installer/Project Configurer/Customer/Security Reviewer] (optionally the ecosystem persona e.g. Python Developers)


I almost think we should remove this field, however I think bringing some of our already existing internal persona definitions into this template might make it easier for people to understand what the field is for, and what values they might want to consider entering here.

loujaybee · 2023-03-03T10:48:42Z

.github/ISSUE_TEMPLATE/epic.yml

-  attributes:
-    label: Growth Area
-    description: Which aspect of Gitpod do we expect improvements in? Acquisition/Onboarding/Exploration/Expansion as defined in [Funnel Proposal](https://www.notion.so/gitpod/Funnel-Proposal-d7d0dba8aced4184b660092a74f8dd3a) (internal)
-    placeholder: Growth is key. This allows us to frame epics from a growth context. Which areas are we expecting this epic to help us with our growth initiatives?


Whilst I believe to be valuable, I don't think the growth area model is well understood in Gitpod right now, I suggest removing, and consider re-adding in future.

thought: Good point—something to consider improving collectively. 💭

.github/ISSUE_TEMPLATE/epic.yml

gtsiolis

Thanks, @loujaybee! 🌮 🌮

It's nice to see our team becoming[1][2] more intentional with issue forms. Looking forward to seeing more changes like this. Left some minor comments and thoughts below.

praise: It's great to see this form becoming more relaxed and easier to use. ✨

issue: One issue I see with this PR is how this breaks the single source of truth (SSOT) for the epic template, as this issue form was initially aiming to duplicate what already exists in PDE / Development Process 2.0 / Epics. ❗

suggestion: I'd suggest replacing the handbook section containing the epic contents with a brief description or a link back to this issue template to maintain a SSOT. 💡

.github/ISSUE_TEMPLATE/epic.yml

gtsiolis · 2023-03-03T11:42:34Z

.github/ISSUE_TEMPLATE/epic.yml

-name: Epic
-description: Create an epic
+name: Epic (User Impacting)
+description: An epic is a grouping of related issues which MUST be delivered together. Epics are as small in scope as reasonably possible, and are "finite" in scope. Please do not use this template for: categorising related work (please instead use labels), investigate work where the solutions is not well defined (e.g. investgiations + spikes), or for technical debt work.


issue: I don't think you can add a description here, right? I also see an error for this line change—probably needs to be moved below in L8.

gtsiolis · 2023-03-03T11:44:32Z

.github/ISSUE_TEMPLATE/epic.yml

 - type: textarea
-  id: summary
+  id: press-release


suggestion: A better alternative could be Release Notes. However, this would require us to be more intentional with this field and how we use it. Let's give it a go.

gtsiolis · 2023-03-03T11:47:44Z

.github/ISSUE_TEMPLATE/epic.yml

  validations:
-    required: true
+    required: false


suggestion: Since we're making this optional it could be nice to stress this is optional in the description above since not every epic will have a press release or announcement bit.

not every epic will have a press release or announcement

Good point. It could be "If this feature would have an announcement, what would it look like from ..."
I think this Press Release section aims to encourage epic authors to explain the value of the feature to everyone regardless of technical background.

gtsiolis · 2023-03-03T11:52:24Z

.github/ISSUE_TEMPLATE/epic.yml

-  attributes:
-    label: Growth Area
-    description: Which aspect of Gitpod do we expect improvements in? Acquisition/Onboarding/Exploration/Expansion as defined in [Funnel Proposal](https://www.notion.so/gitpod/Funnel-Proposal-d7d0dba8aced4184b660092a74f8dd3a) (internal)
-    placeholder: Growth is key. This allows us to frame epics from a growth context. Which areas are we expecting this epic to help us with our growth initiatives?


thought: Good point—something to consider improving collectively. 💭

gtsiolis · 2023-03-03T11:55:40Z

.github/ISSUE_TEMPLATE/epic.yml

-    label: Hypothesis
-    description: If we do X, we expect Y
-    placeholder: Can be useful if the work is explicitly experimental.
+    description: Optionally specifiy which user will be impacted by this change? 


thought: Removing this is also a sign of low maturity level on how we use personas during our product development flow. It would be nice if instead we could reuse and reinforce some past reference work regarding personas, see relevant section in the handbook. 📙

gtsiolis · 2023-03-03T12:00:58Z

.github/ISSUE_TEMPLATE/epic.yml

-    description: If we do X, we expect Y
-    placeholder: Can be useful if the work is explicitly experimental.
+    description: Optionally specifiy which user will be impacted by this change? 
+    placeholder: [Developer/Installer/Project Configurer/Customer/Security Reviewer] (optionally the ecosystem persona e.g. Python Developers)


suggestion: This could list an example or personas and also link back to the single source of truth (SSOT) of the personas list.

gtsiolis · 2023-03-03T12:03:33Z

.github/ISSUE_TEMPLATE/epic.yml

-    label: Press release
-    description: Create excitement about the idea
-    placeholder: Useful if you want to spend the extra time to get stakeholders, the team, or customers excited.
+    description: Optionally make explicit any complexities, e.g. dependencies on other teams, technical challenges, unknowns. 


question: Does it help to have the optionally prefix in the label? If yes, is it accurate to use a comma or prefix it with parenthesis in all text labels? For example:

// Option :A: Optionally, make explicit any complexities, e.g. dependencies on other teams, technical challenges, unknowns. // Option B: (Optional) Make explicit any complexities, e.g. dependencies on other teams, technical challenges, unknowns.

Option B looks good - it gives more emphasis to the part in brackets.

Co-authored-by: André Duarte <[email protected]>

gtsiolis · 2023-03-03T14:42:15Z

To clarify, none of my comments[1][2][3] above are blocking or implying we should fix something before merging this. 💡

The intent behind most comments above was to:

Aim for having a single source of truth (SSOT).
Potentially make that PDE / Development Process 2.0 / Epics section slightly more useful. Cc @karishay
Push us to be more intentional with maintaining such process in the handbook.

Cc @atduarte @laushinka @loujaybee

.github/ISSUE_TEMPLATE/epic.yml

Update epic.yml

3f90c1b

roboquat added do-not-merge/work-in-progress do-not-merge/release-note-label-needed size/M labels Mar 3, 2023

loujaybee marked this pull request as ready for review March 3, 2023 10:45

roboquat removed the do-not-merge/work-in-progress label Mar 3, 2023

loujaybee commented Mar 3, 2023

View reviewed changes

loujaybee changed the title ~~Update epic.yml~~ Refresh + simplify the epic template Mar 3, 2023

loujaybee requested review from gtsiolis and laushinka March 3, 2023 10:50

atduarte reviewed Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Outdated Show resolved Hide resolved

atduarte reviewed Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Outdated Show resolved Hide resolved

atduarte reviewed Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Show resolved Hide resolved

gtsiolis reviewed Mar 3, 2023

View reviewed changes

loujaybee and others added 2 commits March 3, 2023 14:12

Update .github/ISSUE_TEMPLATE/epic.yml

1f7f8d3

Co-authored-by: André Duarte <[email protected]>

Update .github/ISSUE_TEMPLATE/epic.yml

1805e29

Co-authored-by: André Duarte <[email protected]>

loujaybee commented Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Outdated Show resolved Hide resolved

Update .github/ISSUE_TEMPLATE/epic.yml

09bfcd2

loujaybee commented Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Outdated Show resolved Hide resolved

Update .github/ISSUE_TEMPLATE/epic.yml

2b3c538

loujaybee commented Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Outdated Show resolved Hide resolved

Update .github/ISSUE_TEMPLATE/epic.yml

2d033d2

loujaybee commented Mar 3, 2023

View reviewed changes

.github/ISSUE_TEMPLATE/epic.yml Outdated Show resolved Hide resolved

Update .github/ISSUE_TEMPLATE/epic.yml

255c2f2

atduarte approved these changes Mar 21, 2023

View reviewed changes

roboquat added the release-note-none label Mar 21, 2023

roboquat removed the do-not-merge/release-note-label-needed label Mar 21, 2023

roboquat merged commit ff298a4 into main Mar 21, 2023

roboquat deleted the update-epic-template branch March 21, 2023 12:00

Refresh + simplify the epic template #16652

Refresh + simplify the epic template #16652

Uh oh!

Conversation

loujaybee commented Mar 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gtsiolis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gtsiolis commented Mar 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

loujaybee commented Mar 3, 2023 •

edited

Loading

gtsiolis left a comment •

edited

Loading

gtsiolis commented Mar 3, 2023 •

edited

Loading